Deliver held outcomes to a definition that arrives after configure() - #67

What was wrong

Metro loads modules lazily (inlineRequires). So a define() can run after configure(). configure() starts the replay of journaled outcomes. An outcome whose key had no definition yet emitted the unhandled-key row. Then it waited for the next launch. The definition arrived a moment later, but nothing routed the outcome to it.

Diana works around this in openspacelabs/diana#9555. It imports every definition before configure(). The PR "v11: configure() takes the definitions" fixed it with a breaking contract. This PR fixes it without a breaking change.

What changes

Late definitions receive their outcomes. Delivery now holds each outcome whose key has no definition. When define() registers that key, delivery routes the held outcomes again. They take the normal path: wait for a same-id mutate(), run the handler, then ack.

flowchart LR
  A[Outcome replays] --> B{Key defined?}
  B -- yes --> C[Handler, then ack]
  B -- no --> D[Emit unhandled-key row<br/>Hold the outcome]
  D -- "define() of the key" --> E[Join the id's lane<br/>in original order]
  E --> C
  D -- "no define() this session" --> F[Stays unacknowledged<br/>Redelivers next launch]

• The unhandled-key row is still emitted, as before.
• Held outcomes keep their order per id. A held outcome also goes before a later outcome of the same id that already waits in the lane.
• A key that is never defined behaves as before. Its outcome stays unacknowledged for the next launch.
• A define() that replaces a key does not deliver a held outcome twice.
• cancel(id) drops the held outcomes of that id before and after native cancel. On a settled entry, native forgets those outcomes too. So a later define(), also one that runs while native cancels, must not run a handler for them. If native cancel rejects, the outcomes were never acknowledged, so native redelivers them at the next launch.
• The unhandled-key row is not followed by a new state row when the outcome is handled. After the ack, a completed or cancelled entry leaves getRequests() without a state event. An error entry keeps its error row.

Optional configure({ definitions }). It takes the handles that define() returned. Listing a handle imports its module, so its define() runs before the replay. In development, a later define() of a key that is not in the list logs one warning per key:

define: "late" is not in configure({ definitions }). It still receives its outcomes, but list it so that its module loads before configure().

Nothing is rejected. An unlisted key still receives its outcomes, and mutate() does not wait. Without the option, nothing changes. A new exported type, AnyDefined, names one entry of the list. configure() throws only when definitions is not an array of handles.

Where to look

• src/delivery.ts: hold(), release(), forget(), and the drain loop inline in route(). The loop is inline so that no await comes between the last empty check and the key lookup.
• src/index.ts: onDefine() (dev warning and release()), the definitions check in configure(), and the forget() call in cancel().
• src/registry.ts: the new onDefine hook, called after define() registers a key.
• README rules 5, 6 and 8 under "Reliable delivery", and the configure() options table.

Known limit

Order holds among the outcomes of one key. If one id has held outcomes under two keys, the key that is defined first delivers first. A held outcome also goes after a later outcome of the same id whose handler started before the define() ran. Outcomes of one id normally share one key.

Test plan

• yarn test: 6 suites, 214 tests pass (20 new: 12 in client.test.ts, 8 in delivery.test.ts).
• yarn jest in example/RNBGUExample: 1 suite, 4 tests pass.
• yarn typecheck, with a new type test for configure({ definitions }).
• yarn lint:ci.
• With release() disabled, 10 new tests fail. With the drain removed from route(), the lane-order test fails. With await drainReleased() in place of the inline loop, the microtask test fails at depth 1. Without forget() in cancel(), the cancel test fails. With forget() only after native cancel, the test that defines the key during the cancel fails.

🤖 Generated with Claude Code

https://claude.ai/code/session_011y2fcSHHE3i5eQHgATu6Tc